GitHubテンプレートリポジトリでSQLFluffルールを一元管理する

#GitHub
#GitHub Actions
エノカワ
2024.10.19
こんにちは！エノカワです。
SQLFluffは、SQLコードの品質を自動でチェックしてくれるLintツールで、プロジェクトにおいてSQLのスタイルやフォーマットを統一するのに役立ちます。

しかし、各プロジェクトで個別にSQLFluffルールを管理していると、ルールの一貫性が失われたり、ルール変更の際に複数のリポジトリで手動のメンテナンスが必要になるなど、手間が増えることがあります。
そこで、今回はGitHubのテンプレートリポジトリを活用して、SQLFluffルールを一元管理し、他のプロジェクトに自動で適用する方法をご紹介します。
具体的には、以下のステップで進めます：
テンプレートリポジトリにSQLFluffルールファイルを配置
各リポジトリでDeploy Keyを使ってテンプレートリポジトリからルールを取得
GitHub Actionsを使ってmainブランチにプッシュされた際に自動でSQLファイルをLintチェック
 テンプレートリポジトリの作成まず、SQLFluffルールを一元管理するためのテンプレートリポジトリを作成します。
 GitHub で新しいリポジトリを作成GitHub上で新しいリポジトリを作成し、リポジトリ名をsqlfluff-templateとします。
「Template repository」のオプションをチェックして、このリポジトリをテンプレートリポジトリに設定します。
 テンプレートリポジトリからのリポジトリ作成GitHubのテンプレートリポジトリ機能を使って新しいリポジトリを作成することで、SQLFluffのルールも自動的に継承されます。
ただし、テンプレートリポジトリを基に作成されたリポジトリは、作成後にテンプレート側で行われた変更が自動的に反映されないため、注意が必要です。
テンプレートリポジトリの更新内容を最新の状態に保つには、後述するGitHub Actionsで自動的にテンプレートリポジトリからルールファイルを取得する仕組みを取り入れる必要があります。
 SQLFluff ルールファイルの追加次に、SQLFluffのルールを定義するファイルを作成し、テンプレートリポジトリに保存します。
リポジトリ内に.sqlfluffという名前のファイルを作成し、以下のようにルールを記述します。
.sqlfluff
[sqlfluff]
dialect = bigquery
max_line_length = 80

[sqlfluff:layout:type:comma]
line_position = trailing

[sqlfluff:rules:capitalisation.keywords]
capitalisation_policy = lower
ルールファイルをコミットして、テンプレートリポジトリに保存します。
上記の設定では、BigQueryを使用し、キーワードを小文字に統一、行の長さを80文字以内に制限するなどのスタイルルールを指定しています。
 Deploy Keyの設定テンプレートリポジトリから他のリポジトリにルールを取得するために、Deploy Keyを設定します。
Deploy Keyは特定のリポジトリへのSSHアクセス権を付与する鍵で、GitHub Actions内でテンプレートリポジトリのルールを取得するために使用します。
 SSHキーの生成ローカルマシンでSSHキーを生成します。以下のコマンドを使用して、公開鍵と秘密鍵を作成します。
$ ssh-keygen -t rsa -b 4096
秘密鍵は安全に保管し、公開鍵をテンプレートリポジトリに設定します。
 テンプレートリポジトリにDeploy Keyを追加テンプレートリポジトリの「Settings」→「Deploy keys」に移動します。
「Add deploy key」をクリックし、先ほど生成した公開鍵を入力します。
「Allow write access」はチェックせずに、「Add key」をクリックします。
テンプレートリポジトリにDeploy Keyが追加されました。
 リポジトリシークレットの設定Deploy Keyを安全に使用するため、SQLFluffルールを適用したいリポジトリにシークレットとして秘密鍵を保存します。
 リポジトリシークレットの追加SQLFluffルールを適用したいリポジトリに移動します。
「Settings」→「Secrets and variables」→「Actions」に移動し、「New repository secret」をクリックします。
シークレット名をTEMPLATE_REPO_DEPLOY_KEYとし、秘密鍵を入力します。
「Add key」をクリックします。
SQLFluffルールを適用したいリポジトリにシークレットが保存されました。
 シークレットを組織単位で利用する場合もしリポジトリが組織の一部である場合は、シークレットを組織単位で設定し、複数のリポジトリで一元的に管理・参照することができます。
Organization の「Settings」→「Secrets and variables」→「Actions」に移動し、シークレット名をTEMPLATE_REPO_DEPLOY_KEYとし、秘密鍵を入力して保存します。
 GitHub Actionsの設定GitHub Actionsを使って、SQLFluffのLintチェックを自動化します。

これにより、mainブランチにプッシュされた際に自動的にSQLコードがLintされ、ルールに違反した場合は警告が表示されます。
 ワークフローファイルの作成ルールを適用したいリポジトリに.github/workflows/sqlfluff_lint.ymlという名前のファイルを作成し、以下のように設定します。
.github/workflows/sqlfluff_lint.yml
name: SQLFluff Lint

on:
  push:
    branches:
      - main

jobs:
  lint:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.9'

    - name: Install SQLFluff
      run: |
        python -m pip install --upgrade pip
        pip install sqlfluff

    - name: Set up SSH
      uses: webfactory/ssh-agent@v0.9.0
      with:
        ssh-private-key: ${{ secrets.TEMPLATE_REPO_DEPLOY_KEY }}

    - name: Clone SQLFluff Template Repository
      run: |
        git clone git@github.com:{ユーザー名}/sqlfluff-template.git

    - name: Copy SQLFluff Config
      run: |
        cp sqlfluff-template/.sqlfluff .

    - name: Lint SQL files
      run: sqlfluff lint sql/
このワークフローでは、mainブランチにプッシュされるたびに、SQLFluffのルールがテンプレートリポジトリから取得され、SQLファイルがLintされます。
 ワークフローの実行以下のSQLファイルをmainブランチにプッシュしてワークフローをトリガーします。
sql/queries/example_query.sql
SELECT id, name, email FROM users WHERE created_at >= '2023-01-01' AND status = 'active'
ワークフローが正常に実行され、テンプレートリポジトリからルールファイルが正しくコピーされていることを確認します。
以下のようにSQLFluffのLintチェックが実行され、ルールに違反している箇所がリストされます。
Run sqlfluff lint sql/
== [sql/queries/example_query.sql] FAIL
L:   1 | P:   1 | CP01 | Keywords must be lower case. [capitalisation.keywords]
L:   1 | P:   1 | LT05 | Line is too long (88 > 80). [layout.long_lines]
L:   1 | P:   1 | LT09 | Select targets should be on a new line unless there is
                       | only one select target. [layout.select_targets]
L:   1 | P:  24 | CP01 | Keywords must be lower case. [capitalisation.keywords]
L:   1 | P:  35 | CP01 | Keywords must be lower case. [capitalisation.keywords]
L:   1 | P:  68 | CP01 | Keywords must be lower case. [capitalisation.keywords]
All Finished!
Error: Process completed with exit code 1.
 まとめこの記事では、SQLFluffのルールを一元管理するために、GitHubテンプレートリポジトリとDeploy Keyを活用し、GitHub Actionsを使用してLintチェックを自動化する方法を紹介しました。

このアプローチを使用することで、複数のプロジェクトで統一されたSQLスタイルを保ちつつ、ルールの変更を一度に反映させることができます。
 参考デプロイキーの管理 - GitHub Docs
python - Cloning private github repository within organisation in actions - Stack Overflow